import { Alert, CodeGroup } from "@/components/forMdx";

# Jazz database adapter for Better Auth

The package `jazz-tools/better-auth/database-adapter` is a database adapter for Better Auth based on Jazz. Better Auth's data will be stored in CoValues encrypted by [Server Worker](/docs/server-side/setup), synced on our distributed [cloud infrastructure](/cloud).

## Getting started

1. Install and configure [Better Auth](https://www.better-auth.com/docs/installation)
2. Install Jazz package `pnpm jazz-tools`
3. Generate a [worker's credentials](/docs/server-side/setup#generating-credentials)

  <CodeGroup>
  ```bash
  npx jazz-run account create --name "Better Auth Server Worker"
  ```
  </CodeGroup>

  <Alert variant="info" className="mt-4" title="Security">
    Although all workers have the same capabilities, we recommend to use different workers for different purposes. As it will store user's credentials, the best practice is to keep it isolated from other workers.
  </Alert>

4. Setup the database adapter on Better Auth server instance.

  <CodeGroup>
  ```ts auth.ts
  ```
  </CodeGroup>

5. You're ready to use Better Auth features without managing any database by yourself!


## How it works

The adapter automatically creates Jazz schemas from Better Auth's database schema, even if not all the SQL-like features are supported yet. The database is defined as a CoMap with two properties: `group` and `tables`. The first one contains the master Group that will own all the tables; the second one is a CoMap with table names as keys and data as values.

Internally it uses specialized repository for known models like `User`, `Session` and `Verification`, to add indexes and boost performances on common operations.


## How to access the database

The easiest way to access the database is using the same Server Worker's credentials and access the table we're looking for.

<CodeGroup>
```ts index.ts
```
</CodeGroup>


## Rotating the worker's credentials

If you need to change the worker, you can create a new one and add it to the master Group.

<CodeGroup>
```ts rotate-worker.ts
```
</CodeGroup>


<Alert variant="warning" className="mt-4" title="Security">
  Rotating keys means that data stored from that point forward will be encrypted with the new key, but the old worker's secret can still read data written up until the rotation. Read more about encryption in [Server Worker](/docs/reference/encryption).
</Alert>

## Compatibility

The adapter generates Jazz schemas reading from Better Auth's database schema, so it should be compatible with any plugin / user's code that introduces new tables or extends the existing ones.

So far, the adapter has been tested with **Better Auth v1.3.7** with the following plugins:

<table>
  <thead>
    <tr>
      <th>Plugin/Feature</th>
      <th>Compatibility</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><a href="https://www.better-auth.com/docs/authentication/email-password">Email &amp; Password auth</a></td>
      <td>✅</td>
    </tr>
    <tr>
      <td><a href="https://www.better-auth.com/docs/authentication/github">Social Provider auth</a></td>
      <td>✅</td>
    </tr>
    <tr>
      <td><a href="https://www.better-auth.com/docs/plugins/email-otp">Email OTP</a></td>
      <td>✅</td>
    </tr>
  </tbody>
</table>

More features and plugins will be tested in the future.
